UI beginner's guide
This page explains the basic ideas behind and differences between terms like Macros, Scripts and AddOns to those who are beginners to using or making such things. = Slash Commands = To understand how everything else works, you need to know what a Slash Command is. WoW allows you to give simple commands to the game in the form of a slash (/) followed by the name of the command. You can give these commands directly by typing them into the chat box. An example would be the "/follow" command. If you target a friendly and type "/follow" (without the quotes), you start following them. You can get a list of some of the slash commands by typing "/help". There are several types of slash commands. Some are designed to perform game actions (e.g. /follow, /assist, /cast), others are chat related commands (e.g. /yell, /chatlist) or give you information (/who). You also have emotes (/laugh, /bow). Finally, there is one very special slash command "/script", explained later. = Macros = The purpose of a Macro is to allow you to create some very simple custom actions or tasks, based on the existing game actions. A macro is just a sequence of slash commands, which are executed in order when you execute the macro. To create a new macro, either type "/macro" (without the quotes), or click on the speech bubble next to the chat box and select macro. You can then give a macro a name, an icon and type in a few lines of slash commands. The macro is created in the form of an action that you can drag onto your hotbar. You can activate the macro by clicking on the resulting button on the hotbar. An example macro would be: /cast Fireball(Rank 1) /yell "I am frying it!" This macro merely casts a fireball, and then yells for everyone to hear that you have done so. Macros have some severe limitations, and are only intended for very very simple tasks. The most important limitation is that you can not cast more than one spell at a time using a macro. This limitation is there so that macros can't automate too much for you. You can have as many other commands within the 256 character limit as you like. = Scripts = Usually, not just in WoW, the term Script refers to a short to medium length program, written in some kind of simple programming language (called a scripting language). The purpose of a script is usually to control another program. World of Warcraft has a powerful programming language called Lua embedded inside it, which is used for scripting. What this means is that WoW is able to understand and execute little programs written in the Lua language. However, in WoW, a script is usually not something that you use by itself, i.e. you don't just type in a script and execute it (although this is also possible). Instead, there are several places in WoW where you have the option to enter scripts as part of something else. The kind of places that you can use a script in: * /script command : If you type the slash command "/script" in the chat box, you can follow it with one or more valid Lua language statements (i.e. a script), separated by semi-colons ( ; ). * Macros: you can enter scripts as part of macros, by putting one or more "/script" command in your macro. * AddOns: You can read more about these below, but the main point is that these are all created using Lua scripts (and also XML technology, but don't worry about that right now). In all the cases you can use scripts in, the things you can do with the scripts are the same. So what can a script do? There are many resources on Lua scripts. See our page on Lua to find out more about the language. Browse the rest of the Interface Customization page for additional resources. The most important point however is that scripts are able to perform many more game actions than slash commands. This is done via a set of functions (called API or Application Programming Interface) that WoW makes available for use in scripts. There is a quite extensive list of all the API functions available for use in scripts at World of Warcraft API. After all that explanation, here is an example of a script: if (IsPartyLeader()) then CastSpellByName("Fireball(Rank 1)"); end This script is very simple. When you execute this script, if you are the party leader, then you cast a fireball. To use this script, you would have to do so via the "/script" command. e.g.: /script if (IsPartyLeader()) then CastSpellByName("Fireball(Rank 1)"); end You can type this directly into the chat box, or make that line part of a macro, so that it's reusable. In summary: a script in WoW is a short program written in the Lua language, able to interact with the game and perform game actions. You use a script by including it as part of something else, e.g. by putting it in a macro via the /script command, or by putting it in an AddOn. = AddOns = Blizzard has made the decision that the user interface of World of Warcraft is fully customizable, modifiable and extendable. This is completely legal, and is encouraged by Blizzard. A User Interface Modification (UI Mod for short) and AddOn is exactly the same thing, the difference is merely in their names. Usually "Mods" tend to refer to smaller things that only modify existing funcionality of the user interface, whereas AddOns tend to add extra functionality. From here on, we will simply use "AddOn". From a User's point of view From a user's point of view, what you need to know is that AddOns come in the form of one or more text files, ending in the ".toc", ".xml" and ".lua" extensions. These files are supposed to go into a folder called Interface in your World of Warcraft folder, or into one of its sub-folders. Usually AddOns are distributed as zip files by their authors, and you "install" them by simply unzipping them in your World of Warcraft folder. (If you don't see an Interface folder, don't worry. It is not there by default. If you want to put anything into it, you are free to create it yourself). Warning: Be very very careful with AddOns that come as executable ".exe" files. Always triple-check before you use these to make sure that they really do what they say they do, as executable files can do anything whatsoever to your computer. AddOns are supposed to be written in text format in .xml and .lua files, so that anyone can check that there is nothing malicious about them. You have no such check available with executable files. Also, since AddOns only operate within WoW, they can't harm your computer, whereas executable files can. Having said that, some authors do distribute their AddOns as executable files. These executables most of the time don't do more than just unzip the AddOn's files and place them in your WoW folder in the appropriate places. Occasionally the executables are used to automatically download updated versions of the AddOn, or to upload data collected by the AddOn (for example item statistics to be put on a web-site, etc.). Uninstalling: You can always uninstall any AddOn and reset the WoW UI to its clean default state by merely deleting or renaming the Interface, WTF, and WDB folders in your WoW folder, then rebooting. From a Developer's point of view AddOns mainly consist of two types of files: * Lua files, which contain the brunt of the logic * XML files, which define how your dialogs, buttons, etc look. These elements are commonly referred to as "Widgets". You list these files in a TOC (Table Of Contents) file together with some additional parameters. If you've been programming before, you may be used to having your program start, and keep running, until you don't want it to run any more. Not so in WoW. AddOns are event driven, i.e. everything that happens does so in response to an event, e.g. the user clicking one of your buttons, the client receiving a chat message, someone hitting the character, etc. Those events are delivered to widgets, and to grab hold of them, you need to embed little snippets of Lua code in the right places that calls functions in the .lua files. It is possible to implement a whole addon in just the .xml files, but it gets clunky, and you need to HTML-encode < and > characters and so forth. Good places here on WoWWiki to look for more information: * Interface Customization * World of Warcraft API * XML User Interface * AddOns - a guide on how to create an addon from scratch * Category:HOWTOs External guides: * mmhell.com - A Beginner's Guide to Interface Modification (Marian 'Fyrn' R, Aug. 2004) * mmhell.com - Your first AddOn Cosmos, Gypsy, CT_Mod and other AddOn packages If you look around the forums a bit, you will see names like Cosmos, Gypsy and CT_Mod popping up. These are major AddOn packages that contain a large number of UI AddOns. Their authors (often working in teams) are respectable members of the WoW community who have worked hard to create useful (and sometimes not-so-useful) AddOns for your gaming pleasure, and have bundled them together into one easy-to-use package. Feel free to use any and all of these packages. They are legal, Blizzard allows and encourages their use, although you won't get technical support from Blizzard if something is wrong with them. There are many of these around, download and try a few of them and see if you like them. Usually the authors make these packages highly configurable so that you can adjust them to your needs. Note: a lot of these major AddOn packages conflict with each other, so you won't be able to use them together. Standalone, pure AddOns, what's so good about them? You will sometimes see AddOn authors being proud of their AddOn being "standalone", or "pure addon". In the past, often AddOns modified existing UI functionality by changing something in the existing, core UI files provided by Blizzard. This has lead to conflicts as different AddOns all tried to modify the same file. A "pure addon" is one that does not modify any existing files, and merely adds its own files. This is a very good thing, because you can have any number of such AddOns happily coexisting side-by-side. For this reason in WoW patch 1.10, Blizzard has completely disabled the ability to change the core UI files themselves. Therefore, all modifications to the UI can now only be done via pure AddOns. (Note that this doesn't mean that existing functionality of the UI can't be modified, it just means that it has to be done via an AddOn without modifying Blizzard's files themselves). Also, a lot of AddOns depend on other AddOns for their operation. For example, most AddOns in the Cosmos package wouldn't work by themselves, and need the whole Cosmos package to be present to work. A "standalone" AddOn is one that is capable of working by itself, with nothing more than just that one AddOn being present. Again, this is a good thing, because it allows you to pick and choose just those exact AddOns that you want, without having anything you don't want. Many addons are aware of the major addon frameworks though and can interact with them if they're present. Having said that, from the point of view of an AddOn's author, you will find that often a lot of AddOns do very similar sort of things. It is much more easy and quick for an AddOn author to create a new AddOn if they can rely on existing functionality in other AddOns or some common core "libraries". That's why there are AddOns out there that depend on things such as the Sea function library, which in itself is just an AddOn. If you find an AddOn that requires some other core AddOn, don't be afraid of it. Just make sure you also download the core AddOn. = See Also = * The UI FAQ * The AddOns primer * Category:AddOns * Interface Customization Category:Interface Customization Category:FAQs